ODLinkSpec

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODLinkSpec

Superclasses
ODObject
Subclasses
none

An object of the ODLinkSpec class advertises a part's ability to create a link to data it is transferring.

Description
A link specification is a signal that a link can be made from content in a specified source part. The link specification remains valid as long as its source part exists and the document containing it remains opened. After the document is closed, the link specification becomes meaningless.
When a source part that supports linking writes to the clipboard or drag-and-drop object, it uses a link specification to advertise its ability to create a link. The source part creates a link specification by calling its draft's CreateLinkSpec method (page 166), passing as parameters a reference to itself and data sufficient to enable the source part to identify the selected content. The data in a link specification is private to the source part; it is returned to the source part if the part's CreateLink method (page 492) is called to create a link. Because the link specification is valid only during the lifetime of its source part, the data can contain pointers to information maintained by the part.
A link specification provides methods for writing or reading itself to and from a focused storage unit. In addition to writing content to the storage content unit of the data-transfer object (clipboard or drag-and-drop object), the source part calls the link specification's WriteLinkSpec method (page 393) to write the link specification to the kODPropLinkSpec property.
A user who pastes or drops the source data to a destination part can request a link by means of the Paste As dialog box. The destination part creates an empty link specification by calling its draft's CreateLinkSpec method, passing null for the source part and data parameters. The destination part calls the ReadLinkSpec method (page 392) of the empty link specification to read from the kODPropLinkSpec property of the content storage unit. The destination part then creates the link by passing the link specification to its draft's AcquireLink method (page 153), which in turn passes the link specification back to the source part's CreateLink method.
Whenever a source part writes a link specification to the clipboard, it should save clipboard's current update ID, as returned by the clipboard's GetUpdateID method (page 93). The part must remove the link specification from the clipboard when either of the following conditions is true:

It becomes infeasible to create the link, for example, because the potential source content is deleted or modified.
The part's ReleaseAll method (page 468) is called.

The source part can check the clipboard update ID and compare it with the saved ID to determine whether its content is still on the clipboard.
For information on using the clipboard and drag-and-drop object, see the descriptions of the classes ODClipboard (page 83) and ODDragAndDrop (page 187). For further information on the implementation of OpenDoc links, see the descriptions of the companion classes ODLink (page 348) and ODLinkSource (page 371), and the chapter on data transfer in the OpenDoc Programmer's Guide for the MacOS.

Methods
This section presents summary descriptions of the ODLinkSpec methods, followed by detailed descriptions in alphabetical order.

ReadLinkSpec
Initializes this empty link specification by reading its data from the specified focused storage unit.
WriteLinkSpec
Writes the data for this link specification into the specified focused storage unit.

Methods
ReadLinkSpec
WriteLinkSpec